docs(work-items): de-slop instruction surfaces (0.39.13) - #3107

Fifth #2891 de-slop shard: purge em dashes from the claude-config plugin
instruction surfaces, the next-worst cluster after session-flow (#3106),
planning (#3105), work-items (#3107) and source-control (#3108).

Rewrote README.md and all ten SKILL.md files under /ai-slop:audit fix
semantics: periods, commas, a colon before a list, or a restructured
sentence. Never parentheses, en dashes, or a spaced hyphen, since each of
those is the same interruption wearing a different mark. Two review rounds
on the PR caught seven places where a paired em dash had become
parentheses and two doubled-connective run-ons; all were restructured.

Rebased onto 0.39.0. That release restructured audit-instructions/SKILL.md
(moving the Phase D state-key block to context/report-keying.md) and added
--persist-findings, so this shard re-applies to the new text rather than
reverting it: the flag, its Phase D paragraph, and both context/ spokes are
retained, with the em dashes in the new prose purged in the same style.
context/ files stay out of scope, matching #2891's target set and every
prior shard.

Frontmatter description and argument-hint values are rewritten too. No
quoted auto-invocation trigger phrase contained an em dash, so no trigger
changed.

Verification (this repo's .claude/ai-slop.json disables rule-em-dash
corpus-wide, so the detector runs against an isolated HOME and
CLAUDE_PROJECT_DIR to force the rule on):

- detect.sh over the 11 shard files: 482 findings -> 0, every other rule
  also 0
- no en dash or spaced hyphen introduced; the four en dashes in the diff
  are pre-existing numeric ranges (I1-I28, I1-I5, 3-5 lanes)
- check-changelog-parity.sh --check and --check-bump origin/main: pass
- CHECK_SKILL_SKIP_MARKDOWNLINT=1 check-changed-skills.sh origin/main:
  10 skills, 0 errors, every base-ref trigger phrase preserved
- markdownlint-cli2 over the 12 changed files: 0 issues
- audit-instructions/SKILL.md is 483 lines, under the 500-line cap

Pre-existing and not from this diff: three audit-permission-state script
suites fail identically on a clean origin/main worktree in this
environment. This shard touches no script.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro

Fifth #2891 de-slop shard: purge em dashes from the claude-config plugin
instruction surfaces, the next-worst cluster after session-flow (#3106),
planning (#3105), work-items (#3107) and source-control (#3108).

Rewrote README.md and all ten SKILL.md files under /ai-slop:audit fix
semantics: periods, commas, a colon before a list, or a restructured
sentence. Never parentheses, en dashes, or a spaced hyphen, since each of
those is the same interruption wearing a different mark. Two review rounds
on the PR caught seven places where a paired em dash had become
parentheses and two doubled-connective run-ons; all were restructured.

Rebased across two releases that landed on main mid-review, in both cases
re-applying to the newer text rather than reverting it:

- 0.39.0 (#3176) restructured audit-instructions/SKILL.md, moving the
  Phase D state-key block to context/report-keying.md and adding
  --persist-findings. The flag, its Phase D paragraph, and both context/
  spokes are retained.
- 0.39.1 (#3178) normalized setup/SKILL.md and audit-instructions/SKILL.md
  to canonical fleet SSOT wording with PLUGIN-PHILOSOPHY citations. That
  wording and those citations are kept verbatim; only their punctuation is
  de-slopped.

context/ files stay out of scope, matching #2891's target set and every
prior shard.

Frontmatter description and argument-hint values are rewritten too. No
quoted auto-invocation trigger phrase contained an em dash, so no trigger
changed.

Verification (this repo's .claude/ai-slop.json disables rule-em-dash
corpus-wide, so the detector runs against an isolated HOME and
CLAUDE_PROJECT_DIR to force the rule on):

- detect.sh over the 11 shard files: 0 findings, every rule clean
- no en dash or spaced hyphen introduced; the four en dashes in the diff
  are pre-existing numeric ranges (I1-I28, I1-I5, 3-5 lanes)
- check-changelog-parity.sh --check and --check-bump origin/main: pass
- CHECK_SKILL_SKIP_MARKDOWNLINT=1 check-changed-skills.sh origin/main:
  10 skills, 0 errors, every base-ref trigger phrase preserved
- markdownlint-cli2 over the 12 changed files: 0 issues
- audit-instructions/SKILL.md is 484 lines, under the 500-line cap

Pre-existing and not from this diff: three audit-permission-state script
suites fail identically on a clean origin/main worktree in this
environment. This shard touches no script.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro

No linked issue

## Summary

Fourth #2891 de-slop shard: purge em dashes from the `source-control`
plugin instruction surfaces (next-worst cluster after planning,
session-flow, and work-items).

## Fix

Rewrote `plugins/source-control/README.md` and every
`plugins/source-control/**/SKILL.md` under `/ai-slop:audit fix`
semantics (periods, commas, or a restructured sentence; never
parentheses, en dashes, or a spaced hyphen as a stand-in).
Meaning-preserving self-audit repaired multi-line paired asides. The
generated options block is ignore-fenced. Protocol strings in fences and
inline code stay as written. `source-control` 0.54.17. Cheatsheet
refreshed for the rewritten summary.

## Verification

- Detector: 0 `rule-em-dash` findings, 76 declined (generated-options
fence plus fenced/inline-code protocol spans)
- `python3 -m unittest` `test_skill_contract`: 25 tests OK
- `python3 scripts/sync-plugin-options-docs.py --check` up to date
- `scripts/check-changelog-parity.sh --check-bump origin/main` passes
- Quoted trigger phrases vs origin/main: none lost

#2891 stays open. Prior shards: #3105 planning, #3106 session-flow,
#3107 work-items.

## Related

Refs #2891

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

No linked issue

## Summary

Fifth #2891 de-slop shard: purge em dashes from the `claude-config`
plugin instruction surfaces, the
next-worst cluster after `session-flow` (#3106), `planning` (#3105),
`work-items` (#3107) and
`source-control` (#3108). #2891 stays open; ranked by em-dash lines over
non-vendor instruction
surfaces, the next unclaimed cluster after this one is `discipline`
(468), then `claude-ops` (336).

## Fix

Rewrote `README.md` and all ten `SKILL.md` files under `/ai-slop:audit
fix` semantics: em dashes
become periods, commas, a colon before a list, or a restructured
sentence. Never parentheses, en
dashes, or a spaced hyphen, since each of those is the same interruption
wearing a different mark.

A self-review against that guardrail caught seven places where a paired
em dash had become
parentheses in this very diff — four frontmatter `description` values
(`audit`, `audit-instructions`,
`audit-automation-gaps`, `audit-prompting-postures`) and three inline
spots (`setup`'s required-keys
list, `audit-instructions`' I8-family list and its
discover-instruction-surfaces population,
`audit-pass`' exclusion-set aside). All seven were restructured to
commas, a colon, or a sentence
break; the net parenthesis delta across the diff is -1.

Frontmatter `description` and `argument-hint` values are rewritten too.
No quoted auto-invocation
trigger phrase contained an em dash, so no trigger changed.
`claude-config` 0.38.10.

Wording only: no check, phase, gate, lane, contract, or script changed.

## Verification

This repo's `.claude/ai-slop.json` disables `rule-em-dash` corpus-wide
(a deliberate house-style
decision, #3031), so every detector run below pins `HOME` and
`CLAUDE_PROJECT_DIR` to empty
directories to lift that config and force the rule on — the same
isolation the detector's own test
suite uses.

- `detect.sh` over the 11 shard files: **482 `rule-em-dash` findings to
0**, with every other rule
  also reporting 0.
- No en dash or spaced hyphen introduced; net parenthesis delta -1.
- `scripts/check-changelog-parity.sh --check` and `--check-bump
origin/main`: pass.
- `CHECK_SKILL_SKIP_MARKDOWNLINT=1 bash scripts/check-changed-skills.sh
origin/main`: 10 skills,
0 errors. It confirms every base-ref trigger phrase is preserved on all
ten. One soft warning
  (`unhobble` at 201 lines against a 200-line target) is pre-existing.
- `markdownlint-cli2` over the 12 changed files: 0 issues.
- `node scripts/generate-cheatsheet.mjs`: already in sync — no
`metadata.summary` value changed, so
  unlike the `work-items` shard this one needs no cheat-sheet refresh.
- `python3 scripts/sync-plugin-options-docs.py --check`, `typos`,
`editorconfig-checker`: pass.
- `origin/main` merged into the branch before this PR; no conflicts, and
the two new main commits
  (#3115, #3116) touch no `claude-config` file.

**Pre-existing failure, not from this diff.** Three
`audit-permission-state` script suites fail in
this environment: `permission-merge` 19/51, `automode-entry-diff` 3/63,
`managed-conformance` 1/37.
They fail with identical counts on a clean `origin/main` worktree, and
this shard touches no script.
Flagging rather than fixing, since diagnosing them is out of scope here.

## Related

- Refs #2891 — the de-slop campaign this shard advances; stays open for
the remaining clusters.
- Refs #3105, #3106, #3107, #3108 — the sibling instruction-surface
shards.
- Refs #3031 — the measurement and decision that disabled `rule-em-dash`
corpus-wide, which is why
the verification runs force the rule back on rather than trusting a
default run.

**Deferred finding, deliberately not fixed here: manifest `description`
fields are outside the
campaign's scope definition.** Review flagged that
`plugins/claude-config/.claude-plugin/plugin.json`
still carries 5 em dashes in its marketplace-facing `description`. That
is correct, and it is a gap
in #2891's own scoping rather than in this shard: the issue defines the
target set as "every
`SKILL.md`, plugin READMEs, `AGENTS.md`, root `README`", which does not
include `plugin.json`. The
merged `work-items` shard (#3107) touched its manifest for the version
bump only, so every shipped
shard carries the same gap.

Measured across the marketplace: **47 plugins** have em dashes in their
manifest `description`, led
by `discipline` (14), `claude-ops` (12) and `session-flow` (11). Fixing
only `claude-config` here
would leave the shard series internally inconsistent while resolving 5
of ~120 occurrences, so this
belongs to a campaign-level decision on #2891 about whether manifest
descriptions join the target
set, not to this PR. Recorded here so it is not lost.
🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro

---
_Generated by [Claude
Code](https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro)_


---
_Generated by [Claude Code](https://claude.ai/code)_

Run /code-tidying:dissolve-comments (strict) over 22 gate scripts and
suites: 13 files, every edit COMMENT-ONLY. Paired regression records
and basename-bearing suite comments kept (only trimmed). Census delta:
-58 comment lines, -4109 bytes. Suites covering these files pass; the
other failures are environment (worktreeroot.path, htmlhint, strace,
jq on PATH) or fail identically on HEAD.

Removed narrative, verbatim:

- scripts/lib/python-probe.sh: "Three bash wrappers under scripts/ run a Python engine's unittest suite from a bash-only CI step, and each answered the same two questions for itself: what Python does this engine require, and is there an interpreter on this host that meets it. The three copies were byte-identical apart from the engine path, so a fix to either answer had to land three times to be true anywhere." / "the same hazard is documented at length in scripts/lib/changed-files.sh, where two plausible out-var names came back silently empty."
- scripts/cheatsheet-config.mjs: "`,` and `?` were added after a parser sweep found them clearing every rule here while failing a real YAML parse outright (#3189): a leading `,` raises a ParserError and a leading `? ` a ScannerError. They belong to the same c-indicator class as the rest of this set and were simply missing from it." / "(#3189)"
- scripts/check-detector-findings-crosswalk.sh: "This lived as a checklist in the issue that introduced the crosswalk, which would have disappeared when that issue closed. A bar nothing runs is a bar that decays on the first row nobody argues."
- scripts/check-fleet-audit-doc-grammar.sh: "#2646 rebased cleanly and reverted only the skill prose, leaving the parser untouched. Every script-side test stayed green while the skill instructed agents to refuse a valid invocation (claude-code-plugins#2713)." (now: "a revert of either file's half alone keeps every test inside the other green."). .test.sh: "(#2713)" twice, "(the #2646 shape)", "(#2807)".
- scripts/check-hook-userconfig-argv.sh: "the exact regression disk-hygiene shipped through 0.8.x and #1242 fixed."
- scripts/check-lane-coverage.test.sh: "(claude-code-plugins#2839). No git state means the class cannot recur here." / "This is the half that survived the six-job collapse."
- scripts/check-loop-lane-floor-drift.sh: ", and until this script there was none: the section claimed "fleet audits check conformance per consumer" and nothing did." / "The claim's cost was already paid. Two uncoordinated de-slop shards, #3107 (work-items) and #3108 (source-control), rewrote two em dashes inside the staleness bullet of all three lane bodies and touched neither the reader contract that owns the block nor the two other copies. The three lanes stayed byte-identical to EACH OTHER, which is the half a reviewer notices, while all three drifted from their source, which is the half nobody did." / "It is not hypothetical here: the original report of this coupling listed five copies, and building the registry found six." / "was tried first and". .test.sh: ", and this gate's whole reason for existing is that the prose claim it replaces ("fleet audits check conformance per consumer") was exactly that." / "(#2840)" / "This is the historical defect: two de-slop shards rewrote punctuation inside the staleness bullet of the lane bodies and left the source untouched." / "That is the class that produced the original drift: the general copy-drift gate could not see these files either."
- scripts/check-orphaned-fixtures.sh: "the "looks-tested" trap a merged-PR audit caught (autonomy shipped a large security-binding fixture corpus with no eval or test consuming any of it)." / ", the issue's primary consumption path" / "The previous `esc=$(printf '%s' "$base" | sed -E 's/[][\\.|$(){}?+*^]/\\&/g')` paid a printf+sed pipeline per fixture (380 on this tree)." / "Same metacharacter class as that sed." / "autonomy/setup alone has 238 fixtures sharing one grader; a per-fixture jq was 378 execs for 26 files." (now: "many fixtures share one grader.") / "(#3488 class)"
- scripts/affected-tests.test.sh: "(claude-code-plugins#3773, Codex P2)" / "measured at every .js in the repo selecting the same 156 of 439 suites" / "(#3424)"
- scripts/lib/changed-files.sh: "Seven checkers under scripts/ each answered the same two questions for themselves ("is this base ref real?" and "what changed against it?") and the copies drifted. The divergence was live when this file was extracted (#2914, finding 1): check-shell-portability.sh and check-skill-portability.sh carried the NUL-delimited (-z) read that keeps a C-quoted pathname intact, while check-changed-skills.sh and check-docs-only.sh still read `git diff --name-only` line-wise and silently dropped such a path." / "Measured on the unprefixed version, with three distinct broken outcomes and no diagnostic pointing at the caller: an out-var named `base` aborted under `set -u` citing an internal variable, one named `filter` came back holding the option array, and ones named `tmp` or `path` came back SILENTLY EMPTY, the empty-change-set fail-open this file exists to remove."
- scripts/lib/changed-files.test.sh: "(#2914, finding 1), and no caller suite exercised it: the divergence was found by reading, not by a red test."; "now".

Intentional-removal: dissolve-comments pass; removed comment text is recorded above.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UpA569K1JgnKu1jQvRqMjL